From 04248fbd396527661d1d6f2faa46be65155c4df1 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 13 Jan 2011 23:10:25 -0500 Subject: [PATCH] Update some outdated content in the question index Based on a patch by Jasper St. Pierre https://bugzilla.gnome.org/show_bug.cgi?id=639494 --- docs/reference/gtk/question_index.sgml | 369 +++++++++++-------------- 1 file changed, 166 insertions(+), 203 deletions(-) diff --git a/docs/reference/gtk/question_index.sgml b/docs/reference/gtk/question_index.sgml index 2f3b6d3fb5..f807bddb51 100644 --- a/docs/reference/gtk/question_index.sgml +++ b/docs/reference/gtk/question_index.sgml @@ -35,8 +35,8 @@ How do I get started with GTK+? -The GTK+ website offers a -tutorial and a +The GTK+ website offers a +tutorial and a FAQ. More documentation ranging from whitepapers to online books can be found at the GNOME developer's site. @@ -47,7 +47,7 @@ this reference manual for details. -Where can I get help with GTK+, submit a bug report, or make a feature +Where can I get help with GTK+, submit a bug report, or make a feature request? @@ -102,11 +102,11 @@ state (explained in its documentation). -For strings returned from functions, they will be declared "const" (using -#G_CONST_RETURN) if they should not be freed. Non-const strings should be -freed with g_free(). Arrays follow the same rule. (If you find an exception -to the rules, please report a bug to http://bugzilla.gnome.org.) +For strings returned from functions, they will be declared "const" (using +#G_CONST_RETURN) if they should not be freed. Non-const strings should be +freed with g_free(). Arrays follow the same rule. If you find an +undocumented exception to the rules, please report a bug to http://bugzilla.gnome.org. @@ -164,8 +164,8 @@ How do I use GTK+ with threads? -This is covered in the GDK threads -documentation. See also the GThread +This is covered in the GDK threads +documentation. See also the GThread documentation for portable threading primitives. @@ -182,33 +182,37 @@ How do I internationalize a GTK+ program? Most people use GNU gettext, already required in order to install GLib. On a UNIX -or Linux system with gettext installed, type info gettext +or Linux system with gettext installed, type info gettext to read the documentation. -The short checklist on how to use gettext is: call bindtextdomain() so gettext -can find the files containing your translations, call textdomain() to set the -default translation domain, call bind_textdomain_codeset() to request that -all translated strings are returned in UTF-8, then call gettext() to look up -each string to be translated in the default domain. +The short checklist on how to use gettext is: call bindtextdomain() so +gettext can find the files containing your translations, call textdomain() +to set the default translation domain, call bind_textdomain_codeset() to +request that all translated strings are returned in UTF-8, then call +gettext() to look up each string to be translated in the default domain. + + +gi18n.h provides the following shorthand macros for +convenience. Conventionally, people define macros as follows for convenience: - #define _(x) gettext (x) - #define N_(x) x + #define _(x) gettext (x) + #define N_(x) x + #define C_(ctx,x) pgettext (ctx, x) -You use N_() (N stands for no-op) to mark a string for translation in a -context where a function call to gettext() is not allowed, such as in an -array initializer. -You eventually have to call gettext() on the string to actually fetch the -translation. _() both marks the string for translation and actually +You use N_() (N stands for no-op) to mark a string for translation in +a location where a function call to gettext() is not allowed, such as +in an array initializer. +You eventually have to call gettext() on the string to actually fetch +the translation. _() both marks the string for translation and actually translates it. - - -Nowadays, GLib provides the common shorthand macros in the header file -gi18n.h, so you don't have to define them yourself, -just include that header. +The C_() macro (C stands for context) adds an additional context to +the string that is marked for translation, which can help to disambiguate +short strings that might need different translations in different +parts of your program. Code using these macros ends up looking like this: @@ -231,22 +235,22 @@ Code using these macros ends up looking like this: -Libraries using gettext should use dgettext() instead of gettext(), which -allows them to specify the translation domain each time they ask for a -translation. Libraries should also avoid calling textdomain(), since they -will be specifying the domain instead of using the default. For dgettext() -the _() macro can be defined as: +Libraries using gettext should use dgettext() instead of gettext(), which +allows them to specify the translation domain each time they ask for a +translation. Libraries should also avoid calling textdomain(), since +they will be specifying the domain instead of using the default. + + +With the convention that the macro GETTEXT_PACKAGE is +defined to hold your libraries translation domain, +gi18n-lib.h can be included to provide +the following convenience: - #define _(x) dgettext ("MyDomain", x) + #define _(x) dgettext (GETTEXT_PACKAGE, x) - -Again, GLib comes with the gi18n-lib.h, saving you the -trouble of defining the macros by hand. The macros in that header expect the -translation domain to be specified by the %GETTEXT_PACKAGE macro. - @@ -259,9 +263,9 @@ How do I use non-ASCII characters in GTK+ programs ? -GTK+ uses Unicode (more exactly -UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a sequence of -one to six bytes and has a number of nice properties which make it a good +GTK+ uses Unicode (more exactly +UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a sequence of +one to six bytes and has a number of nice properties which make it a good choice for working with Unicode text in C programs: @@ -271,30 +275,30 @@ ASCII characters are encoded by their familiar ASCII codepoints. ASCII characters never appear as part of any other character. -The zero byte doesn't occur as part of a character, so that UTF-8 strings -can be manipulated with the usual C library functions for handling +The zero byte doesn't occur as part of a character, so that UTF-8 strings +can be manipulated with the usual C library functions for handling zero-terminated strings. -More information about Unicode and UTF-8 can be found in the -UTF-8 and Unicode i +More information about Unicode and UTF-8 can be found in the +UTF-8 and Unicode FAQ for Unix/Linux. GLib provides functions for converting strings between UTF-8 and other encodings, see g_locale_to_utf8() and g_convert(). Text coming from external sources (e.g. files or user input), has to be -converted to UTF-8 before being handed over to GTK+. The following example -writes the content of a IS0-8859-1 encoded text file to +converted to UTF-8 before being handed over to GTK+. The following example +writes the content of a IS0-8859-1 encoded text file to stdout: gchar *text, *utf8_text; gsize length; GError *error = NULL; -if (g_file_get_contents (filename, &text, &length, NULL)) +if (g_file_get_contents (filename, &text, &length, NULL)) { - utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1", + utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1", NULL, NULL, &error); if (error != NULL) { @@ -304,7 +308,7 @@ if (g_file_get_contents (filename, &text, &length, NULL)) else g_print (utf8_text); } -else +else fprintf (stderr, "Unable to read file %s\n", filename); @@ -315,36 +319,37 @@ handling non-ASCII content: direct UTF-8 If your editor and compiler are capable of handling UTF-8 encoded sources, -it is very convenient to simply use UTF-8 for string literals, since it allows -you to edit the strings in "wysiwyg". Note that choosing this option may -reduce the portability of your code. +it is very convenient to simply use UTF-8 for string literals, since it +allows you to edit the strings in "wysiwyg". Note that choosing this option +may reduce the portability of your code. escaped UTF-8 -Even if your toolchain can't handle UTF-8 directly, you can still encode string -literals in UTF-8 by using octal or hexadecimal escapes like -\212 or \xa8 to -encode each byte. This is portable, but modifying the escaped strings is not -very convenient. Be careful when mixing hexadecimal escapes with ordinary text; +Even if your toolchain can't handle UTF-8 directly, you can still encode +string literals in UTF-8 by using octal or hexadecimal escapes like +\212 or \xa8 to encode each byte. +This is portable, but modifying the escaped strings is not very convenient. +Be careful when mixing hexadecimal escapes with ordinary text; "\xa8abcd" is a string of length 1 ! runtime conversion -If the string literals can be represented in an encoding which your toolchain -can handle (e.g. IS0-8859-1), you can write your source files in that encoding -and use g_convert() to convert the strings to UTF-8 at runtime. Note that this -has some runtime overhead, so you may want to move the conversion out of inner -loops. +If the string literals can be represented in an encoding which your +toolchain can handle (e.g. IS0-8859-1), you can write your source files +in that encoding and use g_convert() to convert the strings to UTF-8 at +runtime. Note that this has some runtime overhead, so you may want to move +the conversion out of inner loops. -Here is an example showing the three approaches using the copyright sign -© which has Unicode and ISO-8859-1 codepoint 169 and is represented in -UTF-8 by the two bytes 194, 169: +Here is an example showing the three approaches using the copyright sign +© which has Unicode and ISO-8859-1 codepoint 169 and is represented +in UTF-8 by the two bytes 194, 169, or "\302\251" as +a string literal: g_print ("direct UTF-8: ©"); g_print ("escaped UTF-8: \302\251"); @@ -368,9 +373,9 @@ How do I use GTK+ with C++? -There are two ways to approach this. The GTK+ header files use the subset -of C that's also valid C++, so you can simply use the normal GTK+ API -in a C++ program. Alternatively, you can use a "C++ binding" +There are two ways to approach this. The GTK+ header files use the subset +of C that's also valid C++, so you can simply use the normal GTK+ API +in a C++ program. Alternatively, you can use a "C++ binding" such as gtkmm which provides a native C++ API. @@ -380,20 +385,20 @@ connected to signals, not methods. So you will need to use global functions or "static" class functions for signal connections. -Another common issue when using GTK+ directly is that -C++ will not implicitly convert an integer to an enumeration. +Another common issue when using GTK+ directly is that +C++ will not implicitly convert an integer to an enumeration. This comes up when using bitfields; in C you can write the following code: - gdk_window_set_events (gdk_window, + gdk_window_set_events (gdk_window, GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK); while in C++ you must write: - gdk_window_set_events (gdk_window, + gdk_window_set_events (gdk_window, (GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK); @@ -427,19 +432,19 @@ How do I load an image or animation from a file? -To load an image file straight into a display widget, use -gtk_image_new_from_file() If the file load fails, -gtk_image_new_from_file() will display no image graphic — to detect -a failed load yourself, use gdk_pixbuf_new_from_file() directly, then -gtk_image_new_from_pixbuf().. +To load an image file straight into a display widget, use +gtk_image_new_from_file() If the file load fails, +gtk_image_new_from_file() will display no image graphic — to detect +a failed load yourself, use gdk_pixbuf_new_from_file() directly, then +gtk_image_new_from_pixbuf().. To load an image for another purpose, use gdk_pixbuf_new_from_file(). To i load an animation, use gdk_pixbuf_animation_new_from_file(). -gdk_pixbuf_animation_new_from_file() can also load non-animated images, so -use it in combination with gdk_pixbuf_animation_is_static_image() to load a -file of unknown type. +gdk_pixbuf_animation_new_from_file() can also load non-animated images, so +use it in combination with gdk_pixbuf_animation_is_static_image() to load a +file of unknown type. -To load an image or animation file asynchronously (without blocking), use +To load an image or animation file asynchronously (without blocking), use #GdkPixbufLoader. @@ -453,14 +458,13 @@ How do I draw text ? -To draw a piece of text, use a Pango layout and gdk_draw_layout(), -using code like the following: +To draw a piece of text, use a Pango layout and gdk_draw_layout(). layout = gtk_widget_create_pango_layout (widget, text); fontdesc = pango_font_description_from_string ("Luxi Mono 12"); - pango_layout_set_font_description (layout, fontdesc); - gdk_draw_layout (..., layout); + pango_layout_set_font_description (layout, fontdesc); + pango_cairo_show_layout (cr, layout); pango_font_description_free (fontdesc); g_object_unref (layout); @@ -485,13 +489,13 @@ How do I measure the size of a piece of text ? -To obtain the size of a piece of text, use a Pango layout and +To obtain the size of a piece of text, use a Pango layout and pango_layout_get_pixel_size(), using code like the following: layout = gtk_widget_create_pango_layout (widget, text); fontdesc = pango_font_description_from_string ("Luxi Mono 12"); - pango_layout_set_font_description (layout, fontdesc); + pango_layout_set_font_description (layout, fontdesc); pango_layout_get_pixel_size (layout, &width, &height); pango_font_description_free (fontdesc); g_object_unref (layout); @@ -510,21 +514,21 @@ section of Pango manua -Why are types not registered if I use their GTK_TYPE_BLAH +Why are types not registered if I use their GTK_TYPE_BLAH macro ? -The GTK_TYPE_BLAH macros are defined as calls to +The GTK_TYPE_BLAH macros are defined as calls to gtk_blah_get_type(), and the _get_type() i functions are declared as %G_GNUC_CONST which allows the compiler to optimize the call away if it appears that the value is not being used. -A common workaround for this problem is to store the result in a volatile +A common workaround for this problem is to store the result in a volatile variable, which keeps the compiler from optimizing the call away. volatile GType dummy = GTK_TYPE_BLAH; @@ -543,7 +547,7 @@ How do I create a transparent toplevel window ? To make a window transparent, it needs to use a visual which supports that. -This is done by getting the RGBA colormap of the screen with +This is done by getting the RGBA colormap of the screen with gdk_screen_get_rgba_colormap() and setting it on the window. Note that gdk_screen_get_rgba_colormap() will return %NULL if transparent windows are not supported on the screen; also note that this may change from @@ -563,8 +567,8 @@ gdk_draw_rgb_32_image(). Note that the presence of an RGBA visual is no guarantee that the -window will actually appear transparent on screen. On X11, this -requires a compositing manager to be running. See +window will actually appear transparent on screen. On X11, this +requires a compositing manager to be running. See gtk_widget_is_composited() for a way to find out if the alpha channel will be respected. @@ -583,7 +587,7 @@ channel will be respected. See tree widget overview — you -should use the #GtkTreeView widget. (A list is just a tree with no branches, +should use the #GtkTreeView widget. (A list is just a tree with no branches, so the tree widget is used for lists as well). @@ -600,8 +604,8 @@ See text widget overview — you should use the #GtkTextView widget. -If you only have a small amount of text, #GtkLabel may also be appropriate -of course. It can be made selectable with gtk_label_set_selectable(). For a +If you only have a small amount of text, #GtkLabel may also be appropriate +of course. It can be made selectable with gtk_label_set_selectable(). For a single-line text entry, see #GtkEntry. @@ -615,8 +619,8 @@ single-line text entry, see #GtkEntry. -#GtkImage can display images in just about any format GTK+ understands. -You can also use #GtkDrawingArea if you need to do something more complex, +#GtkImage can display images in just about any format GTK+ understands. +You can also use #GtkDrawingArea if you need to do something more complex, such as draw text or graphics over the top of the image. @@ -648,17 +652,14 @@ How do I change the color of a widget? -See gtk_widget_modify_fg(), gtk_widget_modify_bg(), gtk_widget_modify_base(), -and gtk_widget_modify_text(). See GTK+ -resource files for more discussion. You can also change widget color -by installing a resource file and parsing it with gtk_rc_add_default_file(). -The advantage of a resource file is that users can then override the -color you've chosen. +See gtk_widget_override_color() and gtk_widget_override_background_color(). +You can also change the appearance of a widget by installing a +custom style provider, see gtk_style_context_add_provider(). -To change the background color for widgets such as #GtkLabel that have -no background, place them in a #GtkEventBox and set the background of the -event box. +To change the background color for widgets such as #GtkLabel that +have no background, place them in a #GtkEventBox and set the background +of the event box. @@ -668,35 +669,38 @@ How do I change the font of a widget? -This has several possible answers, depending on what exactly you want to -achieve. One option is gtk_widget_modify_font(). Note that this function -can be used to change only the font size, as in the following example: +This has several possible answers, depending on what exactly you want to +achieve. One option is gtk_widget_override_font(). PangoFontDesc *font_desc = pango_font_description_new (); pango_font_description_set_size (font_desc, 40); - gtk_widget_modify_font (widget, font); + gtk_widget_override_font (widget, font); pango_font_description_free (font_desc); -If you want to make the text of a label larger, you can use +If you want to make the text of a label larger, you can use gtk_label_set_markup(): gtk_label_set_markup (label, "<big>big text</big>"); -This is preferred for many apps because it's a relative size to the -user's chosen font size. See g_markup_escape_text() if you are +This is preferred for many apps because it's a relative size to the +user's chosen font size. See g_markup_escape_text() if you are constructing such strings on the fly. You can also change the font of a widget by putting - gtk-font-name = "Sans 30" + .my-widget-class { + font: Sans 30; + } -in a resource file and parsing it with gtk_rc_add_default_file(). -The advantage of a resource file is that users can then override the font you -have chosen. See GTK+ resource files -for more discussion. +in a CSS file, loading it with gtk_css_provider_load_from_file(), and +adding the provider with gtk_style_context_add_provider_for_screen(). +To associate this style information with your widget, set a style class +on its #GtkStyleContext using gtk_style_context_add_class(). +The advantage of this approach is that users can then override the font +you have chosen. See the #GtkStyleContext documentation for more discussion. @@ -706,8 +710,9 @@ for more discussion. How do I disable/ghost/desensitize a widget? - In GTK+ a disabled widget is termed "insensitive." See -gtk_widget_set_sensitive(). + +In GTK+ a disabled widget is termed "insensitive." +See gtk_widget_set_sensitive(). @@ -746,14 +751,14 @@ How do I make a text widget display its complete contents in a specific font? -If you use gtk_text_buffer_insert_with_tags() with appropriate tags to select -the font, the inserted text will have the desired appearance, but text typed -in by the user before or after the tagged block will appear in the default -style. +If you use gtk_text_buffer_insert_with_tags() with appropriate tags to +select the font, the inserted text will have the desired appearance, but +text typed in by the user before or after the tagged block will appear in +the default style. -To ensure that all text has the desired appearance, use gtk_widget_modify_font() -to change the default font for the widget. +To ensure that all text has the desired appearance, use +gtk_widget_override_font() to change the default font for the widget. @@ -770,17 +775,17 @@ A good way to keep a text buffer scrolled to the end is to place a mark at the end of the buffer, and give it right gravity. The gravity has the effect that text inserted at the mark gets inserted before, keeping the mark -at the end. +at the end. - + To ensure that the end of the buffer remains visible, use gtk_text_view_scroll_to_mark() to scroll to the mark after inserting new text. -The gtk-demo application contains an example of this technique. +The gtk-demo application contains an example of this technique. @@ -797,25 +802,10 @@ How do I associate some data with a row in the tree? -Remember that the #GtkTreeModel columns don't necessarily have to be displayed. -So you can put non-user-visible data in your model just like any other data, -and retrieve it with gtk_tree_model_get(). See the -tree widget overview. - - - - - - -What's the #GtkTreeView equivalent of gtk_clist_find_row_from_data()? - - - - -As there is no separate data column in the #GtkTreeModel, there's no -built in function to find the iter from data. You can write a custom -searching function to walk the tree and find the data, or use -gtk_tree_model_foreach(). +Remember that the #GtkTreeModel columns don't necessarily have to be +displayed. So you can put non-user-visible data in your model just +like any other data, and retrieve it with gtk_tree_model_get(). +See the tree widget overview. @@ -827,9 +817,9 @@ How do I put an image and some text in the same column? -You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn -using gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end(). -So pack both a #GtkCellRendererPixbuf and a #GtkCellRendererText into the +You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn +using gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end(). +So pack both a #GtkCellRendererPixbuf and a #GtkCellRendererText into the column. @@ -837,15 +827,15 @@ column. -I can set data easily on my #GtkTreeStore/#GtkListStore models using +I can set data easily on my #GtkTreeStore/#GtkListStore models using gtk_list_store_set() and gtk_tree_store_set(), but can't read it back? Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel -interface. Consequentially, the can use any function this interface -implements. The easiest way to read a set of data back is to use +interface. Consequentially, you can use any function this interface +implements. The easiest way to read a set of data back is to use gtk_tree_model_get(). @@ -857,14 +847,14 @@ How do I change the way that numbers are formatted by #GtkTreeView? Use gtk_tree_view_insert_column_with_data_func() -or gtk_tree_view_column_set_cell_data_func() and do the conversion from i -number to string yourself (with, say, g_strdup_printf()). +or gtk_tree_view_column_set_cell_data_func() and do the conversion +from number to string yourself (with, say, g_strdup_printf()). The following example demonstrates this: -enum +enum { DOUBLE_COLUMN, N_COLUMNS @@ -873,11 +863,11 @@ enum GtkListStore *mycolumns; GtkTreeView *treeview; -void +void my_cell_double_to_text (GtkTreeViewColumn *tree_column, - GtkCellRenderer *cell, + GtkCellRenderer *cell, GtkTreeModel *tree_model, - GtkTreeIter *iter, + GtkTreeIter *iter, gpointer data) { GtkCellRendererText *cell_text = (GtkCellRendererText *)cell; @@ -892,7 +882,7 @@ my_cell_double_to_text (GtkTreeViewColumn *tree_column, g_free (text); } -void +void set_up_new_columns (GtkTreeView *myview) { GtkCellRendererText *renderer; @@ -908,7 +898,7 @@ set_up_new_columns (GtkTreeView *myview) /* Create a new column that has a title ("Example column"), * uses the above created renderer that will render the double - * value into text from the associated model's rows. + * value into text from the associated model's rows. */ column = gtk_tree_view_column_new (); gtk_tree_view_column_set_title (column, "Example column"); @@ -922,10 +912,10 @@ set_up_new_columns (GtkTreeView *myview) */ /* Set up a custom function that will be called when the column content * is rendered. We use the func_data pointer as an index into our - * model. This is convenient when using multi column lists. + * model. This is convenient when using multi column lists. */ gtk_tree_view_column_set_cell_data_func (column, renderer, - my_cell_double_to_text, + my_cell_double_to_text, (gpointer)DOUBLE_COLUMN, NULL); } @@ -953,42 +943,15 @@ How do I use cairo to draw in GTK+ applications ? -Use gdk_cairo_create() to obtain a cairo context for drawing -on a GDK window or pixmap. See Cairo -Interaction for some more useful functions. - - - - - -I have created a cairo context with gdk_cairo_create(), but when I -later use it, my drawing does not show up. Why is that ? - - - - -All drawing in GTK+ is normally done in an expose handler, and GTK+ -creates a temporary pixmap for double-buffering the drawing. If you -create a cairo context outside the expose handler, it is backed -by the GDK window itself, not the double-buffering pixmap. Consequently, -any drawing you do with that cairo context gets overwritten at the -end of the expose handler, when the double-buffering pixmap is copied -back. +The #GtkWidget::draw signal gets a ready-to-use cairo context +as parameter that you should use. -Possible solutions to this problem are: - - -Turn off double-buffering, with gtk_widget_set_double_buffered(). -This is not ideal, since it can cause some flickering. - - -Create the cairo context inside the expose handler. If you do this, -gdk_cairo_create() arranges for it to be backed by the double-buffering -pixmap. This is the preferred solution, and is used throughout GTK+ -itself. - - +All drawing in GTK+ is normally done in a draw handler, and GTK+ +creates a temporary pixmap for double-buffering the drawing. +It is possible to turn off double-buffering, with +gtk_widget_set_double_buffered(), but this is not ideal, +since it can cause some flickering. @@ -996,7 +959,7 @@ itself. Can I improve the performance of my application by using the -Glitz backend of cairo ? +Glitz or GL backend of cairo ? @@ -1016,7 +979,7 @@ Can I use cairo to draw on a #GdkPixbuf ? No, at least not yet. The cairo image surface does not support the -pixel format used by GdkPixbuf. +pixel format used by GdkPixbuf. -- 2.30.2